Saltar al contenido principal

Patrones de diseño: Atomic Design + Feature-Sliced

CampoValor
StatusAceptado
EncargadosDanieles
Fecha11-05-2026
ProyectoAplicación React Native (MVP móvil + expansión web)

Contexto y problema​

Se está desarrollando una aplicación con React Native cuyo MVP está orientado a plataforma móvil, pero con la expectativa de extenderse a web en el corto-mediano plazo. Es necesario definir desde el inicio un patrón de diseño que:

  • Maximice la reutilización de código entre móvil y web.
  • Permita escalar el proyecto sin deuda técnica desde el MVP.
  • Evite dispersar lógica de plataforma (Platform.OS) por toda la base de código.
  • Facilite el trabajo en equipo con límites de responsabilidad claros entre módulos.

Impulsores de decisiones​

  • ¿Qué tan importante es la reutilización de componentes?
  • ¿El patrón permite aislar las diferencias de plataforma sin contaminar la lógica de negocio?
  • ¿Cuánto overhead introduce durante el MVP, cuando el equipo es pequeño y el tiempo es crítico?

Opciones consideradas​

Opción 1: Atomic Design + Feature-Sliced Architecture (con Platform Abstraction Layer) Seleccionada​

Combina la organización visual jerárquica de Atomic Design (átomos → moléculas → organismos) con Feature-Sliced Architecture para la lógica de negocio, más una capa de abstracción de plataforma para aislar diferencias entre móvil y web.

Ventajas

  • Alta reutilización: shared/ y features/ son agnósticos de plataforma.
  • Boundaries claros: cada capa tiene reglas de importación explícitas.
  • Escalable: agregar features nuevas no afecta las existentes.
  • Platform Abstraction Layer elimina if (Platform.OS) del código de negocio.
  • Compatible con Expo Router, Zustand y TanStack Query.
  • Facilita testing unitario por feature. Desventajas
  • Mayor setup inicial comparado con una arquitectura flat.
  • Requiere disciplina del equipo para respetar las reglas de importación.
  • Puede parecer over-engineered en las primeras semanas del MVP.

Opción 2: Arquitectura plana (por tipo de archivo)​

Organización tradicional donde los archivos se agrupan por tipo: components/, screens/, hooks/, services/, utils/.

Ventajas

  • Setup inmediato, sin overhead inicial.
  • Familiar para la mayoría de desarrolladores React.
  • Válido para proyectos pequeños o prototipos rápidos. Desventajas
  • Escala muy mal: components/ crece sin estructura.
  • Dificulta encontrar todo lo relacionado a una feature.
  • Acoplamiento alto entre partes del sistema.
  • Agregar soporte web obliga a refactorizar toda la estructura.
  • No tiene mecanismo natural para aislar diferencias de plataforma.

Opción 3: Monorepo con Nx o Turborepo​

Separar el código en un monorepo con packages independientes: @app/mobile, @app/web, @app/shared.

Ventajas

  • Separación física clara entre plataformas.
  • Permite builds independientes y CI optimizado.
  • Ideal para equipos grandes con ownership separado. Desventajas
  • Overhead de configuración muy alto para un MVP.
  • Complejidad operacional innecesaria con un equipo pequeño.
  • El beneficio real se percibe con 3+ equipos trabajando en paralelo.
  • Puede bloquear el avance en etapas tempranas del proyecto.

Resultado de la decisión​

Se selecciona la Opción 1: Atomic Design + Feature-Sliced Architecture con Platform Abstraction Layer.

Esta combinación ofrece el mejor balance entre estructura sostenible y velocidad de desarrollo para el MVP. La separación en shared/, features/, screens/ y platform/ permite que la mayor parte del código sea 100% compartido entre móvil y web, mientras que la Platform Abstraction Layer concentra las diferencias de plataforma en un único lugar, evitando que contaminen la lógica de negocio.

La regla de importación unidireccional (shared → features → screens ← platform) garantiza que el proyecto escale sin generar dependencias circulares o acoplamiento implícito entre módulos.

Consecuencias positivas​

  • Más del 80% del código (lógica de negocio, estado, UI base) es reutilizable entre móvil y web sin modificación.
  • Incorporar soporte web en el futuro solo requiere implementar las interfaces de platform/, no refactorizar features.
  • Los nuevos desarrolladores tienen guías claras sobre dónde colocar cada tipo de código.
  • El testing es más simple: cada feature es un módulo independiente sin efectos secundarios externos.
  • Compatibilidad garantizada con el stack elegido: Expo Router (navegación), Zustand (estado), TanStack Query (data fetching) y React Hook Form (formularios).
  • La estructura evita el crecimiento caótico de carpetas que ocurre con arquitecturas planas.

Consecuencias negativas​

  • La semana 1–2 del proyecto se invierte en configurar la estructura base antes de entregar features visibles.
  • Se requiere una sesión de onboarding para que todos los miembros del equipo comprendan y respeten las reglas de importación entre capas.
  • Para proyectos muy pequeños (1–2 pantallas), la estructura puede sentirse más compleja de lo necesario.
  • Sin enforcement automático (e.g., ESLint con import boundaries), las reglas dependen de la disciplina del equipo.